/*
 * Copyright (C) 2025 Tsingteng MicroSystem
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
#ifndef _NFC_HEX_UTILS_H_
#define _NFC_HEX_UTILS_H_

#include <stddef.h>
#include <stdint.h>
#include <stdbool.h>

/**
 * @file nfc_hex_utils.h
 * @brief 十六进制字符串转换工具函数声明
*/

/**
 * @brief 将字符转换为对应的字节值
 *
 * 将给定的字符转换为对应的字节值，并将结果存储在提供的指针所指向的变量中。
 *
 * @param c 字符
 * @param out 存储转换结果的变量指针
 *
 * @return 如果转换成功，返回 true；否则返回 false
 */
bool ctob(char c, uint8_t *out);

/**
 * @brief 将十六进制字符串转换为字节数组
 *
 * 将给定的十六进制字符串转换为字节数组，并将结果存储在输出参数中。
 *
 * @note 字符串长度必须为偶数，否则将返回 0
 * @note 字符串中只能包含十六进制字符，否则返回的长度为已转换的字节数
 *
 * @param hex 十六进制字符串
 * @param len 字符串长度
 * @param out 输出字节数组（需要有至少 len/2 大小的空间）
 *
 * @return 转换后的字节数组长度
 */
size_t hex_to_bytes(const char *hex, size_t len, uint8_t *out);

/**
 * @brief 将字节转换为十六进制字符串
 *
 * 将给定的字节数组转换为十六进制字符串，并将结果存储在输出字符串中。
 * 字符串最后面会添加一个 '\0' 字符。
 *
 * @param bytes 字节数组指针
 * @param len 字节数组长度
 * @param out 输出字符串指针（需要至少有 len*2 + 1 长度的空间）
 *
 * @return 转换后的十六进制字符串长度（包含最后的'\0'字符）
 */
size_t bytes_to_hex(const uint8_t *bytes, size_t len, char *out);

#endif // _NFC_HEX_UTILS_H_
